        _______________________________
       |                               |
       |           MES Viewer          |
       |_______________________________|
           Wersja 1.0.1   2005-10-08


Wstp
=====

MES Viewer to program sucy do ogldania z zewntrz lub w przekroju
trjwymiarowych siatek elementw skoczonych, jak rwnie animacji zmieniajcych
si w czasie wartoci ich wzw. Nie pozwala na edytowanie tych siatek ani nie
potrafi niczego liczy. Jest amatorski, ma jedynie charakter prezentacyjny i
obsuguje wycznie wasny, tekstowy format pliku siatek.

Do programu doczone s trzy przykadowe siatki rnej wielkoci. Pierwsza i
najmniejsza jest sporzdzona rcznie, a pozostae wygenerowane za pomoc
doczonego rwnie do pakietu generatora.


Wymagania
=========

- System operacyjny: Microsoft Windows
- Biblioteka graficzna: Microsoft DirectX 9.0c + plik d3dx9_27.dll
  (do cignicia np. z http://www.toymaker.info/Games/html/d3dx_dlls.html)
- Sprzt: jaka sensowna karta graficzna z akceleracj 3D


Szczegy techniczne
====================

Wczytywanie siatki i inne czynnoci inicjalizacyjne s wykonywane w osobnym
wtku tak, e na ten czas aplikacja nie przestaje odpwiada, mona obserwowa
postp oraz mona przerwa ten proces.

Jako podzia przestrzeni zastosowane zostao swobodne drzewo semkowe (opis np.
w "Perekach programowania gier", tom I, Mark DeLoura, Helion 2002). Trudno byo
dobra optymalny wspczynnik rozszerzenia prostopadocianu, a jak si okazao,
ma on kluczowe znaczenie dla wydajnoci. Ostatecznie dobrany zosta empirycznie
na przykadzie jednej dosy duej siatki.

Najtrudniejsza do napisania bya procedura generowania geometrii powstaej
z przecicia siatki paszczyzn. Wspomogem si mechanizmem sprztowym "Custom
Clipping Plane", natomiast reszt wykonuje prawie 300-linijkowa funkcja
GenerateClipBuffers w pliku Engine.cpp. Przydaaby si jej bardziej szczegowa
optymalizacja.


Uruchamianie
============

Program mona uruchomi na dwa sposoby:

1. Uruchomi MES_View.exe i w oknie wyboru pliku, ktre si pojawi, wybra plik
   MES.
2. Uruchomi program z parametrem podajc od razu nazw pliku z siatk, np.:
   MES_View.exe Zadanie_1_male.mes

Aby posuy si generatorem, naley po prostu uruchomi plik Generator.exe.
Jest to aplikacja konsolowa, ktra dopiero podczas dziaania zadaje pytania i
pozwala na wprowadzenie potrzebnych parametrw generowanej siatki.

Generator suy do generowania przykadowych siatek. Potrafi generowa tylko
elementy szecienne, cho program pozwala na ogldanie siatek zoonych
z elementw skoczonych o dowolnym ksztacie. Wartoci dla poszczeglnych klatek
czasu s generowane prostym automatem komrkowym. Oczywicie, wszystkie te dane
maj jedynie charakter przykadowy i nie ilustruj jakiegokolwiek prawdziwego
obiektu ani zjawiska fizycznego.


Sterowanie
==========

Dostpne w programie klawisze sterujce to:

- przecignicie LPM   obracanie modelu
- przecignicie PPM   przyblianie-oddalanie paszczyzny przecinajcej
- W                    wcza-wycza pokazywanie siatki elementw
  Jeli program si zacina i dziaa wolno, naley pokazywanie siatki wyczy,
  bo jej renderowanie znacznie obnia wydajno (karty graficzne wolniej
  renderuj tryb szkieletowy, ni zapenione trjkty)
- O                    przecza widok perspektywiczny-ortogonalny
- L                    wcza-wycza owietlenie kierunkowe
- Enter, ESC           uruchamia-zatrzymuje animacj
  Pena animacja trwa 10 sekund.
- Home, End            przesuwa czas na pocztek-koniec
- PgUp, PgDn           przesuwa czas wczeniej-pniej szybko
- lewo, prawo          przesuwa czas wczeniej-pniej wolno
- `                    otwiera-zamyka konsol

Wybrane polecenia konsoli:

- mode <szeroko> <wysoko> <odswieanie> <peny-ekran>
  Zmienia tryb graficzny, np.:
  mode 1024 768 100 true

- tree
  Pokazuje, ile elementw trafio do wzw swobodnego drzewa semkowego
  na ktrym poziomie.

Wyj z programu mona zamykajc po prostu jego okno - przyciskiem lub
konbinacj klawiszy Alt+F4.


Format MES
==========

Poniewa nie udao mi si dotrze do adnych przykadowych siatek elementw
skoczonych, ktre byyby trjwymiarowe, wymyliem na potrzeby tego programu
wasny format tych siatek. Pliki nosz rozszerzenie MES i s to pliki tekstowe
zapisane w 1-bajtowym kodowaniu ISO-8859-1. S dokumentami w formacie XNL2
(mj wasny jzyk opisu, http://programex.risp.pl/?strona=xnl2). Oto ich budowa:

1. Nagwek - linijka:

   MES

2. Wierzchoki
   Znane te jako wzy siatki. Zapisane s ich wsprzdne (pozycje)
   w przestrzeni 3D. Pozycje okrelaj liczby zmiennoprzecinkowe, a ich zakres
   jest dowolny - program je przeskalowuje.

   VERTICES
   <liczba-wierzchokw>

   <x0> <y0> <z0>
   <x1> <y1> <z1>
   ...

3. Elementy
   Kady element moe mie dowolny ksztat, a opisany jest za pomoc listy
   trjktw (w dowolnej iloci), ktre tworz jego ciany. Kady trjkt to
   indeksy trzech wierzchokw (w kolejnoci jak na licie wierzchokw powyej,
   wierzchoki indeksowane s od 0).
   
   ELEMENTS
   <liczba-elementw>

   <e0-tr0-i1> <e0-tr0-i2> <e0-tr0-i3>, <e0-tr1-i1> <e0-tr1-i2> <e0-tr1-i3>, ...
   <e1-tr0-i1> <e1-tr0-i2> <e1-tr0-i3>, <e1-tr1-i1> <e1-tr1-i2> <e1-tr1-i3>, ...
   ...

4. Klatki animacji
   S to momenty czasu, dla ktrych okrelone s wartoci liczbowe dla kadego
   wierzchoka. Mog one reprezentowa pewn wielko np. temperatur,
   naprenie, gsto, cinienie itd. S to liczby zmiennoprzecinkowe, a ich
   zakres jest dowolny - s przez program przeskalowywane. Podobnie z wielkoci
   czasu.
   
   FRAMES
   <liczba-ramek>

   <czas0>	<warto-wierzchoka-0> <warto-wierzchoka-1> ...
   <czas1>	<warto-wierzchoka-0> <warto-wierzchoka-1> ...
   ...

Wartoci s prezentowane jako kolory tczy od niebieskiego, poprzez zielony,
ty do czerwonego. Wartoci pomidzy wierzchokami w przestrzeni oraz pomidzy
okrelonymi momentami czasu s przez program interpolowane liniowo.

Dla kadego elementu jego trjkty musz tworzy zamknit bry przestrzenn.
Program sam znajduje brzegi siatki jako trjkty, ktre nale tylko do jednego
elementu. Algorytm dziaa poprawnie wycznie wtedy, gdy midzy elementami nie
ma t-jointw, np.:
   _______________
  |_______|       |
  |_______|_______|

Oraz gdy trjkty ssiednich elementw tworzce czworoktn cian nie s
zwrcone w przeciwne strony (ich przektne nie przecianaj si na krzy).
W przeciwnym wypadku program gupieje, co objawia si znacznym spadkiem
wydajnoci.


Autor
=====

Adam Sawicki
mailto:regedit@risp.pl
http://www.regedit.risp.pl/
gg:2272474


Od autora
=========

Zastrzegam, e nie znam si na metodzie elementw skoczonych. Program napisaem
w cigu 8 dni, jaki swoisty eksperyment i wiczenie matematyczno-informatyczne.
Wykorzystaem do niego mj szkielet silnika 3D, ktry stale rozwijam (Katie
Engine - http://www.regedit.risp.pl/katie/). Projekt nie bdzie kontynuowany.
Wracam teraz do ciekawszych rzeczy :)


Znane bdy
===========

- Czarne kropeczki, ktre pojawiaj si w siatkach z maych elementw
  Wynikaj z niedokadnoci liczb zmiennoprzecinkowych, a do ich zwalczenia
  potrzeba byoby dodatkowego kodu.

- Biae kreseczki, ktre pojawiaj si, kiedy wczona jest siatka
  Wynikaj z uycia mechanizmu Z-BIAS i trudno je cakowicie wyeliminowa.

- Czasami rczne sterowanie przestaje dziaa (Enter i ESC dziaaj)
  To wredny bad wewntrz samego szkieletu aplikacji - program po przywrceniu
  sdzi, e nadal jest nieaktywny.

- Brzydki efekt na paszczynie przecinajcej przy przejciu kolorw
  Wynika ze sposobu konstrukcji bufora wierzchokw i indeksw dla paszczyzny
  przecianajcej - trzebaby opracowa lepszy algorytm jej generowania.

Co monaby doda:

- Legend ze skal kolorw i odpowiadajcymi im wartociami.

- Moliwo kliknicia w dowolne miejsce i podgldnicia, jakiej pozycji X, Y, Z
  oraz jakiej wartoci na siatce ono odpowiada.

- Inne palety kolorw do wyboru, ni domylna tczowa.

Moliwe dalsze optymalizacje:

- Lepszy dobr wspczynnika rozszerzania dla swobodnego drzewa semkowego,
  by moe zaleny od iloci czy redniej wielkoci elementw.

- Optymalizacje procedury przecinajcej - jest napisana w miar dobrze, ale nie
  bya dalej optymalizowana, bo ju nie starczyo mi si (samo jej napisanie
  byo wyzwaniem na 3 dni).


Historia wersji
===============

Wersja 1.0.1 (2005-10-08)
- Poprawiony wielki bd, ktry ogromnie zmniejsza wydajno programu
- Poprawki w dokumentacji
- Przykadowe siatki wygenerowane od nowa

Wersja 1.0 (2005-10-07)
Pierwsza wersja
